Create Your First Doc

Now it is time to create your first doc and update your Gruntfile.js file to include in the compiling and rendering during the grunt "docular" task.

  1. Add a new documentation "group" to include by updating the Gruntfile.js file
    module.exports = function(grunt) {
    
        // Project configuration.
        grunt.initConfig({
    
            pkg: grunt.file.readJSON('package.json'),
    
            docular: {
                groups: [
                    {
                        groupTitle: 'My Test Docs',
                        groupId: 'mytestdocs',
                        groupIcon: 'icon-book',
                        sections: []
                    }
                ],
                showDocularDocs: true,
                showAngularDocs: true
            }
    
        });
    
        // Load the plugin that provides the "docular" tasks.
        grunt.loadNpmTasks('grunt-docular');
    
        // Default task(s).
        grunt.registerTask('default', ['docular']);
    
    };
    
  2. Navigate to the root of your project
    cd <your project root>
  3. Create a directory for your new documentation and navigate within the new directory
    mkdir docs
    cd docs
    
  4. Create a file to hold standard doc text
    touch test.doc
    
  5. Edit this new file and add the following text and save
    @doc overview
    @name Test Documentation Overview
    @description This is my test description!
    Notice it is multiline and supports the "Showdown" implementation of Markdown.
    You can add
    ## Sub headings
    
    You can also create numbered listes among other markdown items
    
    1. Item one
    2. Item two
    <pre>
    some command or script line
    </pre>
    
  6. Update the Gruntfile.js file to include this new file within a new section within the group. Since it is documentation not within comments within a script, we include it in the "docs" array of the section configuration
    module.exports = function(grunt) {
    
        // Project configuration.
        grunt.initConfig({
    
            pkg: grunt.file.readJSON('package.json'),
    
            docular: {
                groups: [
                    {
                        groupTitle: 'My Test Docs',
                        groupId: 'mytestdocs',
                        groupIcon: 'icon-book',
                        sections: [
                            {
                                id: "overviewdocs",
                                title:"My Overview Docs",
                                scripts: [],
                                docs: ['docs/']
                            }
                        ]
                    }
                ],
                showDocularDocs: true,
                showAngularDocs: true
            }
    
        });
    
        // Load the plugin that provides the "docular" tasks.
        grunt.loadNpmTasks('grunt-docular');
    
        // Default task(s).
        grunt.registerTask('default', ['docular']);
    
    };
    
  7. Now let's create your first script file that contains documentation. Let's create a scripts directory for your script.
    cd <root of your project>
    mkdir scripts
    cd scripts
    touch test.js
    
  8. Now edit the test.js file you created within the scripts folder at the root of your document
    /**
    * @doc module
    * @name firstmodule
    * @description This is the definition of the module.
    * It provides information about the module when the name of the
    * module is clicked
    */
    
    /**
    * @doc function
    * @name firstmodule.class:myClass
    * @description This is a function that is classified as a "class"
    * within the module "firstmodule" with name myClass.
    * @param {string} stringInput A description of the stringInput for this function
    * @returns {number} Some number value description
    */
    
    /**
     * Here I can still include inline comments for other developers
     * that are not included in the docs
     */
    var myClass = function (stringInput) {
        return 1;
    };
    
  9. Update the Gruntfile.js file to include this file within the scripts configuration
    module.exports = function(grunt) {
    
        // Project configuration.
        grunt.initConfig({
    
            pkg: grunt.file.readJSON('package.json'),
    
            docular: {
                groups: [
                    {
                        groupTitle: 'My Test Docs',
                        groupId: 'mytestdocs',
                        groupIcon: 'icon-book',
                        sections: [
                            {
                                id: "overviewdocs",
                                title:"My Overview Docs",
                                scripts: ['scripts/'],
                                docs: ['docs/']
                            }
                        ]
                    }
                ],
                showDocularDocs: true,
                showAngularDocs: true
            }
    
        });
    
        // Load the plugin that provides the "docular" tasks.
        grunt.loadNpmTasks('grunt-docular');
    
        // Default task(s).
        grunt.registerTask('default', ['docular']);
    
    };
    
  10. Run the grunt docular task to compile your documentation!
    cd <your project root>
    grunt docular
    
  11. Spin up the local server to view your docs
    grunt docular-server
    
  12. Navigate your browser to the url shown after executing the grunt docular-server task